CAC Advanced API

Objective

The CAC Advanced API returns information about a company and its stakeholders.

Info

The Corporate Affairs Commission (CAC) is a Nigerian government body responsible for regulating and managing companies in the country. The CAC assigns a Registration Certificate (RC) number to each business that registers with them.

Input	Output
The RC Number or name of the company	The details corresponding to the given RC. The complete list of output fields is provided under the Success Response Details section.

API Endpoint

cacAdvanced

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the complete information on the parameter used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`RC`	The company's name or RC Number	Mandatory	Not Applicable	Not Applicable

Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/cacAdvanced' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "RC": "<Enter_the_RC_number>"
}'

Success Response

The following code is a success response from the API.

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "status": "<Status_Of_Response>",
        "message": "<Message_Describing_Response>",
        "timestamp": "<Timestamp_Of_Response>",
        "data": [
            {
                "id": "<Unique_ID>",
                "surname": "<Surname_Of_stakeholder>",
                "firstname": "<First_Name_Of_stakeholder>",
                "otherName": "<Other_Name_Of_stakeholder>",
                "email": "<Email_Address>",
                "phoneNumber": "<Phone_Number>",
                "gender": "<Gender>",
                "formerNationality": "<Former_Nationality>",
                "age": "<Age>",
                "city": "<City>",
                "occupation": "<Occupation>",
                "formerName": "<Former_Name>",
                "corporationName": "<Corporation_Name>",
                "rcNumber": "<Registration_Number>",
                "corporationCompany": "<Corporation_Company>",
                "state": "<State>",
                "pobox": "<Post_Box>",
                "accreditationnumber": "<Accreditation_Number>",
                "isLawyer": "<Is_Lawyer>",
                "lastVisit": "<Last_Visit_Count>",
                "formType": "<Form_Type>",
                "isPresenter": "<Is_Presenter>",
                "isChairman": "<Is_Chairman>",
                "numSharesAlloted": "<Number_Of_Shares_Allotted>",
                "typeOfShares": "<Type_Of_Shares>",
                "dateOfBirth": "<Date_Of_Birth>",
                "status": "<Status>",
                "dateOfTermination": "<Date_Of_Termination>",
                "dateOfAppointment": "<Date_Of_Appointment>",
                "dateOfChangeOfAddress": "<Date_Of_Address_Change>",
                "formerAddress": "<Former_Address>",
                "formerPostal": "<Former_Postal>",
                "formerSurname": "<Former_Surname>",
                "formerFirstName": "<Former_First_Name>",
                "formerOtherName": "<Former_Other_Name>",
                "dateOfStatusChange": "<Date_Of_Status_Change>",
                "identityNumber": "<Identity_Number>",
                "identityIssueState": "<Identity_Issue_State>",
                "otherDirectorshipDetails": "<Other_Directorship_Details>",
                "portalUserFk": "<Portal_User_FK>",
                "affiliatesFk": "<Affiliates_FK>",
                "processTypeFk": {
                    "id": "<Process_Type_ID>",
                    "name": "<Process_Type_Name>",
                    "description": "<Process_Type_Description>",
                    "amount": "<Amount>",
                    "type": "<Type>",
                    "productId": "<Product_ID>",
                    "bankCode": "<Bank_Code>"
                },
                "company": "<Company>",
                "samePersonAsFk": "<Same_Person_As_FK>",
                "natureOfAppOrDischarge": "<Nature_Of_Appointment_Or_Discharge>",
                "isDesignated": "<Is_Designated>",
                "endOfAppointment": "<End_Of_Appointment>",
                "appointedBy": "<Appointed_By>",
                "dateOfDeedOfDischarge": "<Date_Of_Deed_Of_Discharge>",
                "dateOfResolution": "<Date_Of_Resolution>",
                "countryFk": {
                    "id": "<Country_ID>",
                    "name": "<Country_Name>",
                    "code": "<Country_Code>"
                },
                "countryOfResidence": "<Country_Of_Residence>",
                "isCarriedOverFromNameAvai": "<Is_Carried_Over_From_Name_Available>",
                "lga": "<Local_Government_Area>",
                "corporationRegistrationDate": "<Corporation_Registration_Date>",
                "isCompanyDeleted": "<Is_Company_Deleted>",
                "governmentOrganisationName": "<Government_Organisation_Name>",
                "foreignOrganisationName": "<Foreign_Organisation_Name>",
                "companyStreetAddress": "<Company_Street_Address>",
                "companyState": "<Company_State>",
                "companyCity": "<Company_City>",
                "isCorporate": "<Is_Corporate>",
                "countyOfIncorporationFk": "<County_Of_Incorporation_FK>",
                "nationality": "<Nationality>",
                "address": "<Address>",
                "postcode": "<Postcode>",
                "streetNumber": "<Street_Number>",
                "affiliatesResidentialAddress": "<Affiliates_Residential_Address>",
                "affiliatesPscInformation": "<Affiliates_PSC_Information>",
                "legalOwnersOfInterests": [],
                "legalOwnersOfVotingRights": [],
                "stockExchangeSoes": [],
                "approvedForNoticeOfPsc": "<Approved_For_Notice_Of_PSC>",
                "companyAddress2": "<Company_Address_Line_2>",
                "affiliateTypeFk": {
                    "id": "<Affiliate_Type_ID>",
                    "name": "<Affiliate_Type_Name>",
                    "description": "<Affiliate_Type_Description>"
                },
                "fullAddress2": "<Full_Address_Line_2>"
            }
        ]
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

Parameter	Type	Description
id	string	The unique identity number for the company
surname	string	The surname of the stakeholder
firstname	string	The first name of the stakeholder
otherName	string	The other name/ middle name of the stakeholder
email	string	The email address of the stakeholder
phoneNumber	string	The phone number of the stakeholder
gender	string	The gender of the stakeholder
formerNationality	string	The former nationality of the stakeholder
age	integer	The age of the stakeholder
dateOfBirth	string	The date of birth of the stakeholder
city	string	The city of residence of the stakeholder
state	string	The state of residence of the stakeholder
occupation	string	The occupation of the stakeholder
formerName	string	The former name of the stakeholder
formerSurname	string	The former surname of the stakeholder
formerFirstName	string	The former first name of the stakeholder
formerOtherName	string	The former other name of the stakeholder
corporationName	string	The name of the corporation/company
rcNumber	string	The RC number of the corporation
corporationCompany	string	The corporation information
pobox	string	The address details of the shareholder
formerAddress	string	The previous postal address of the shareholder
formerPostal	string	The previous postal address of the shareholder
dateOfChangeOfAddress	string	The date of the change of address
occupation	string	The occupation of the Shareholder
accreditionnumber	string	The accreditation number of the shareholder
isLawyer	boolean	Indicates if the shareholder is a lawyer
lastVisit	integer	The timestamp of last visit
isPresenter	boolean	Indicates if the shareholder is a presenter
isChairman	boolean	Indicates if the shareholder is a chairman
numSharesAlloted	integer	The number of shares allotted to the shareholder
typeOfShares	string	The type of shares allotted
status	string	The current status of the shareholder (ACTIVE/INACTIVE)
dateOfTermination	string	The date of termination of the shareholder
dateOfAppointment	string	The date of appointment of the shareholder
identityNumber	string	The identity number of the shareholder
identityIssueState	string	The state of issue of the identity number of the shareholder
otherDirectorshipDetails	string	The details of other directorships held by the shareholder
natureOfAppOrDischarge	string	The type of application/discharge of the shareholder
isDesignated	boolean	Indicates if the shareholder has a designation in the company
endOfAppointment	string	The date of end of appointment
appointedBy	string	The name of the person who appointed the individual
dateOfDeedOfDischarge	string	The date of deed of discharge
dateOfResolution	string	The date of resolution of the company
isCarriedOverFromNameAvai	boolean	Indicates if the record was carried over from a name availability check
corporationRegistrationDate	string	The registration date of the corporation
isCompanyDeleted	boolean	Indicates if the company has been deleted
governmentOrganisationName	string	The name of the government organisation
foreignOrganisationName	string	The name of the foreign organisation
companyStreetAddress	string	The street address of the company
companyState	string	The state in which the company is located
companyCity	string	The city in which the company is located
isCorporate	boolean	Indicates if the entity is a corporate body
affiliatesResidentialAddress	string	The details of affiliates residential address
legalOwnersOfInterests	string	The details of legal owners of the company
legalOwnersOfVotingRights	string	The details of owners that have voting rights
stockExchangeSoes	string	The details of stock exchange SOEs
approvedForNoticeOfPsc	boolean	Indicates if approved for notice of PSC
affiliateTypeFk	string	The details of the affiliate type

Error Responses

Input Validation Error - Empty RC
Missing/Invalid Credentials
Input Validation Error - Invalid ID Number
Internal Server Error

{
    "message": "RC is not allowed to be empty",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "message": "We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again",
    "statusCode": 404,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	RC is not allowed to be empty	The RC field in the request is empty
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again.	Invalid company name or RC number. Mismatch in input RC number length.
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

Objective​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​